一款支持自动流水线和客户端缓存的 Go 语言 Redis 客户端
Rueidis 是一款高性能的 Go 语言 Redis 客户端，它支持自动流水线操作和服务端辅助客户端缓存等功能。Rueidis 的目标是提供一个简单易用、性能卓越的 Redis 客户端库，以满足 Go 开发者的各种需求。
主要功能
自动流水线操作，提升非阻塞命令的执行效率 服务端辅助客户端缓存，大幅降低延迟和提高吞吐量 支持泛型对象映射和客户端缓存 提供缓存策略模式（Cache-Aside pattern）的实现 支持分布式锁和客户端缓存 提供用于编写测试的 Rueidis 模拟库 集成 OpenTelemetry，方便监控和追踪 支持 Pub/Sub、分片 Pub/Sub 和 Streams 兼容 Redis Cluster、Sentinel、RedisJSON、RedisBloom、RediSearch、RedisTimeseries 等 提供不依赖 Redis Stack 的概率数据结构
快速入门
package main
import (
"context"
"github.com/redis/rueidis"
)
func main() {
client, err := rueidis.NewClient(rueidis.ClientOption{InitAddress: []string{"127.0.0.1:6379"}})
if err != nil {
panic(err)
}
defer client.Close()
ctx := context.Background()
// SET key val NX
err = client.Do(ctx, client.B().Set().Key("key").Value("val").Nx().Build()).Error()
// HGETALL hm
hm, err := client.Do(ctx, client.B().Hgetall().Key("hm").Build()).AsStrMap()
}
命令构建器
Rueidis 提供了简单易用的命令构建器，方便开发者构建 Redis 命令。
client.B().Set().Key("key").Value("val").Nx().Build()
流水线操作
自动流水线操作
Rueidis 会自动将并发执行的非阻塞 Redis 命令进行流水线操作，以减少网络往返次数和系统调用次数，从而提高吞吐量。
func BenchmarkPipelining(b *testing.B, client rueidis.Client) {
b.RunParallel(func(pb *testing.PB) {
for pb.Next() {
client.Do(context.Background(), client.B().Get().Key("k").Build()).ToString()
}
})
}
手动流水线操作
除了自动流水线操作外，Rueidis 还支持手动流水线操作。
cmds := make(rueidis.Commands, 0, 10)
for i := 0; i < 10; i++ {
cmds = append(cmds, client.B().Set().Key("key").Value("value").Build())
}
for _, resp := range client.DoMulti(ctx, cmds...) {
if err := resp.Error(); err != nil {
panic(err)
}
}
服务端辅助客户端缓存
Rueidis 默认开启了服务端辅助客户端缓存的 opt-in 模式，开发者可以通过 DoCache() 或 DoMultiCache() 方法使用该功能。
client.DoCache(ctx, client.B().Hmget().Key("mk").Field("1", "2").Cache(), time.Minute).ToArray()
client.DoMultiCache(ctx,
rueidis.CT(client.B().Get().Key("k1").Cache(), 1*time.Minute),
rueidis.CT(client.B().Get().Key("k2").Cache(), 2*time.Minute))
上下文取消
client.Do()、client.DoMulti()、client.DoCache() 和 client.DoMultiCache() 方法都支持上下文取消，如果上下文被取消或超时，这些方法会提前返回。
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
client.Do(ctx, client.B().Set().Key("key").Value("val").Nx().Build()).Error() == context.DeadlineExceeded
发布/订阅
Rueidis 提供了 client.Receive() 方法来接收来自 Redis 频道的信息。
err = client.Receive(context.Background(), client.B().Subscribe().Channel("ch1", "ch2").Build(), func(msg rueidis.PubSubMessage) {
// 处理接收到的信息
})
CAS 事务
Rueidis 支持 CAS 事务，即 WATCH + MULTI + EXEC 操作。
client.Dedicated(func(c rueidis.DedicatedClient) error {
c.Do(ctx, c.B().Watch().Key("k1", "k2").Build())
c.Do(ctx, c.B().Mget().Key("k1", "k2").Build())
c.DoMulti(
ctx,
c.B().Multi().Build(),
c.B().Set().Key("k1").Value("1").Build(),
c.B().Set().Key("k2").Value("2").Build(),
c.B().Exec().Build(),
)
return nil
})
Lua 脚本
Rueidis 提供了 NewLuaScript 和 NewLuaScriptReadOnly 方法来创建 Lua 脚本。
script := rueidis.NewLuaScript("return {KEYS[1],KEYS[2],ARGV[1],ARGV[2]}")
list, err := script.Exec(ctx, client, []string{"k1", "k2"}, []string{"a1", "a2"}).ToArray()
流式读取
Rueidis 提供了 client.DoStream() 和 client.DoMultiStream() 方法来流式读取 Redis 的响应数据。
s := client.DoMultiStream(ctx, client.B().Get().Key("a{slot1}").Build(), client.B().Get().Key("b{slot1}").Build())
for s.HasNext() {
n, err := s.WriteTo(io.Discard)
if rueidis.IsRedisNil(err) {
// ...
}
}
内存消耗
Rueidis 的每个底层连接都会分配一个环形缓冲区用于流水线操作，缓冲区的大小由 ClientOption.RingScaleEachConn 选项控制，默认值为 10，即每个环形缓冲区的大小为 2^10 字节。
如果 Rueidis 连接过多，可能会占用大量内存。在这种情况下，可以考虑将 ClientOption.RingScaleEachConn 选项的值减小到 8 或 9，但这样做可能会降低吞吐量。
创建 Redis 客户端
可以使用 NewClient 函数创建 Rueidis 客户端，并指定各种选项。
// 连接到单个 Redis 节点
client, err := rueidis.NewClient(rueidis.ClientOption{
InitAddress: []string{"127.0.0.1:6379"},
})
// 连接到 Redis 集群
client, err := rueidis.NewClient(rueidis.ClientOption{
InitAddress: []string{"127.0.0.1:7001", "127.0.0.1:7002", "127.0.0.1:7003"},
ShuffleInit: true,
})
Redis URL
可以使用 ParseURL 或 MustParseURL 函数解析 Redis URL，并将其转换为 ClientOption 结构体。
// 连接到 Redis 集群
client, err = rueidis.NewClient(rueidis.MustParseURL("redis://127.0.0.1:7001?addr=127.0.0.1:7002&addr=127.0.0.1:7003"))
任意命令
如果需要构建 Rueidis 命令构建器中没有提供的 Redis 命令，可以使用 client.B().Arbitrary() 方法。
// 这将生成 [ANY CMD k1 k2 a1 a2] 命令
client.B().Arbitrary("ANY", "CMD").Keys("k1", "k2").Args("a1", "a2").Build()
处理 JSON、原始字节数组和向量相似度搜索
Rueidis 命令构建器将所有参数都视为 Redis 字符串，这意味着开发者可以将 []byte 直接存储到 Redis 中，而无需进行转换。
client.B().Set().Key("b").Value(rueidis.BinaryString([]byte{...})).Build()
命令响应解析
Rueidis 提供了一系列方法来解析 Redis 命令的响应数据，例如 ToString()、AsInt64()、ToArray() 等。
// GET 命令
client.Do(ctx, client.B().Get().Key("k").Build()).ToString()
client.Do(ctx, client.B().Get().Key("k").Build()).AsInt64()
使用 DecodeSliceOfJSON 解析 JSON 数组
DecodeSliceOfJSON 函数可以将 Redis 响应中的 JSON 数组解析为 Go 结构体切片。
type User struct {
Name string `json:"name"`
}
// ...
var users []*User
if err := rueidis.DecodeSliceOfJSON(client.Do(ctx, client.B().Mget().Key("user1", "user2").Build()), &users); err != nil {
return err
}